import { Message } from 'semantic-ui-react'

export const meta = {
  title: 'Migration Guide to v3',
  prevPage: { title: 'Prototypes', href: '/prototypes' },
}

This is a reference for upgrading your application to v3 of Semantic UI React.

<Message
  info
  size='tiny'
  header='Looking to upgrade your app to v2?'
  content={
    <>
      Migration guide to Semantic UI React is available <a href='/migration-guide-v-2'>here</a>.
    </>
  }
/>

## Native ref support

<Message
  compact
  content='This change can be considered as improvement. You should not be affected if you did not used `ref` on Semantic UI React components.'
  header='Risk: low'
  size='mini'
  color='teal'
/>

The main change in v3 is the support of [native refs to components](https://react.dev/reference/react/forwardRef) to avoid usage of [deprecated `ReactDOM.findDOMNode()`](https://react.dev/reference/react-dom/findDOMNode). It means that `ref` prop can be used to get a reference to the underlying DOM element instead of a React component instance.

For example, you can use `ref` to get a reference to the underlying DOM element of `Button` component:

```jsx
import { Button } from 'semantic-ui-react'

const App = () => {
  const buttonRef = React.useRef()

  React.useEffect(() => {
    console.log(buttonRef.current)
  }, [])

  return <Button ref={buttonRef} />
}
```

All components from Semantic UI React v3 support native ref forwarding.

### Note on `Button`, `Input`, `TextArea`

`Button`, `Input` and `TextArea` implemented some methods like `focus()` and `blur()` on their class instances. However, now you will get a reference to the underlying DOM element instead of a React component instance. You should be able to call these methods directly on the DOM element without any issues.

## Removal of `Ref` component

<Message
  compact
  content='You will be affected if you use `Ref` component.'
  header='Risk: high'
  size='mini'
  color='orange'
/>

Because of the native ref support, `Ref` component is no longer needed and was removed as it used deprecated APIs.

```diff
function App() {
-  return (
-    <Ref innerRef={buttonRef}>
-      <Button />
-    </Ref>
-  )
+  return <Button ref={buttonRef} />
}
```

As we exported `Ref` component and recommended its usage everywhere we moved out `Ref` component to a separate package (`@semantic-ui-react/component-ref`). This means that you can use it already with both v2 & v3 to make the upgrade smoother.

```diff
-import { Ref } from "semantic-ui-react";
+import Ref from "@semantic-ui-react/component-ref";
```

<Message compact size='tiny' warning>
  `@semantic-ui-react/component-ref` is considered as a deprecated package, we don't plan maintain
  it, so please consider migration anyway. It also will not receive fixes related to usage of
  deprecated APIs from React.
</Message>

More details on this change in [Semantic-Org/Semantic-UI-React#4286](https://github.com/Semantic-Org/Semantic-UI-React/pull/4286).

## Removal of `Visibility` component

<Message
  compact
  content='You will be affected if you use `Visibility` component.'
  header='Risk: high'
  size='mini'
  color='orange'
/>

The main reason is performance that is far away from native APIs. We suggest to use [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) directly or via React wrappers, for example: [react-intersection-observer](https://www.npmjs.com/package/react-intersection-observer).

As it's not a straightforward replacement that may cause issues with adoption we moved out `Visibility` component to a separate package (`@semantic-ui-react/component-visibility`). This means that you can use it already with v2 or upcoming v3:

```diff
-import { Visibility } from "semantic-ui-react";
+import Visibility from "@semantic-ui-react/component-visibility";
```

<Message compact size='tiny' warning>
  `@semantic-ui-react/component-visibility` is considered as a deprecated package, we don't plan
  maintain it, so please consider migration anyway. It also will not receive fixes related to usage
  of deprecated APIs from React.
</Message>

More details on this change in [Semantic-Org/Semantic-UI-React#4257](https://github.com/Semantic-Org/Semantic-UI-React/pull/4257).

### Removal of static properties on `Transition` component

<Message
  compact
  content='These properties were never referenced in documentation or suggested to be used.'
  header='Risk: negligible'
  size='mini'
  color='green'
/>

Some static properties on `Transition` component were removed:

```diff
-  static INITIAL = TRANSITION_STATUS_INITIAL
-  static ENTERED = TRANSITION_STATUS_ENTERED
-  static ENTERING = TRANSITION_STATUS_ENTERING
-  static EXITED = TRANSITION_STATUS_EXITED
-  static EXITING = TRANSITION_STATUS_EXITING
-  static UNMOUNTED = TRANSITION_STATUS_UNMOUNTED
```

This properties should not be used in public APIs, but it's still a breaking change.
